<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>Inform Annotations</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
		<meta name="viewport" content="width=device-width initial-scale=1">
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<meta http-equiv="Content-Language" content="en-gb">

<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
		
	</head>
	<body class="commentary-font">
		<nav role="navigation">
		<h1><a href="../index.html"><img src="../docs-assets/Inform.png" height=72> </a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=0> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="https://github.com/ganelson/inweb"><img src="../docs-assets/github.png" height=0> inweb</a></li>
<li><a href="https://github.com/ganelson/intest"><img src="../docs-assets/github.png" height=0> intest</a></li>
</ul>
		</nav>
		<main role="main">
		<!-- Weave of 'Inform Annotations' generated by inweb -->
<div class="breadcrumbs">
    <ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inter</a></li><li><a href="index.html#M">Manual</a></li><li><b>Inform Annotations</b></li></ul></div>
<p class="purpose">The standard set of symbol annotations used within Inform.</p>

<ul class="toc"><li><a href="M-ia.html#SP1">&#167;1. Status</a></li><li><a href="M-ia.html#SP2">&#167;2. Translation</a></li><li><a href="M-ia.html#SP3">&#167;3. Append</a></li><li><a href="M-ia.html#SP4">&#167;4. Assimilation markers</a></li><li><a href="M-ia.html#SP5">&#167;5. Miscellaneous code-generation storage</a></li></ul><hr class="tocbar">

<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. Status.</b>The Inter specification allows for any number of annotations to be used;
none are required. The ones listed below are those used in the Inform toolchain
at present.
</p>

<p class="commentary">As a general guideline, annotations are best used for temporary storage during
complex operations (optimisation, code generation, and so on), rather than for
information which changes the functionality of a program. But this is only a
guideline, and several of the cases below could be argued to break it.
</p>

<p class="commentary">What is certainly true is that we want to avoid annotations if there are better
ways to achieve the same thing. At one time there were over 30 in use, but the
figure is now below 10.
</p>

<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. Translation.</b>The final code we generate is itself (probably) the source code of a program
in some other language &mdash; C, for example. That means that most of the symbols
in our Inter program will be "translated" into identifiers in that final
program. For example, the Inter declaration:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> BakersDozen = </span><span class="constant-syntax">13</span>
</pre>
<p class="commentary">might ultimately be compiled to:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    #</span><span class="identifier-syntax">define</span><span class="plain-syntax"> </span><span class="identifier-syntax">CON_019900_BKRSDZN</span><span class="plain-syntax"> </span><span class="constant-syntax">13</span>
</pre>
<p class="commentary">An exaggerated example, perhaps, but the point is that it's normally none of
our business what identifiers the final code-generator chooses to use.
</p>

<p class="commentary">However, we can override its choice like so:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> BakersDozen = </span><span class="constant-syntax">13</span><span class="plain-syntax"> </span><span class="identifier-syntax">__translation</span><span class="plain-syntax">=</span><span class="string-syntax">"BAKERS_DOZEN"</span>
</pre>
<p class="commentary">And now it would come out as:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    #</span><span class="identifier-syntax">define</span><span class="plain-syntax"> </span><span class="identifier-syntax">BAKERS_DOZEN</span><span class="plain-syntax"> </span><span class="constant-syntax">13</span>
</pre>
<p class="commentary">The <span class="extract"><span class="extract-syntax">__translation</span></span> annotation is sometimes added by the final code-generator
itself, to keep track of its translation decisions, but can also be added by
the Inform 7 front-end compiler. Ideally it wouldn't ever do so, but this is
the only sensible way to implement the low-level language feature:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">The</span><span class="plain-syntax"> </span><span class="identifier-syntax">tally</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax"> </span><span class="identifier-syntax">that</span><span class="plain-syntax"> </span><span class="identifier-syntax">varies</span><span class="plain-syntax">. </span><span class="identifier-syntax">The</span><span class="plain-syntax"> </span><span class="identifier-syntax">tally</span><span class="plain-syntax"> </span><span class="identifier-syntax">translates</span><span class="plain-syntax"> </span><span class="identifier-syntax">into</span><span class="plain-syntax"> </span><span class="identifier-syntax">Inter</span><span class="plain-syntax"> </span><span class="identifier-syntax">as</span><span class="plain-syntax"> </span><span class="string-syntax">"SHAZAM"</span><span class="plain-syntax">.</span>
</pre>
<p class="commentary">And this is in turn is a feature we can't simply abolish, or not without
inventing some similar bodge, because it's needed in order to reconcile the
natural-language names for certain standard properties (e.g., "lighted")
with their kit-source equivalents (e.g. <span class="extract"><span class="extract-syntax">lit</span></span>).
</p>

<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. Append.</b>Like the <span class="extract"><span class="extract-syntax">insert</span></span> instruction (see <a href="M-dpiti.html" class="internal">Data Packages in Textual Inter</a>), the
<span class="extract"><span class="extract-syntax">__append</span></span> annotation subverts Inter by writing some code in raw Inform 6
syntax. This can be added to any definition of an instance of an object type,
or to the type itself.
</p>

<p class="commentary">For example, the I7 source text:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">Include</span><span class="plain-syntax"> (- </span><span class="identifier-syntax">has</span><span class="plain-syntax"> </span><span class="identifier-syntax">door</span><span class="plain-syntax">, -) </span><span class="identifier-syntax">when</span><span class="plain-syntax"> </span><span class="identifier-syntax">defining</span><span class="plain-syntax"> </span><span class="identifier-syntax">a</span><span class="plain-syntax"> </span><span class="identifier-syntax">door</span><span class="plain-syntax">.</span>
</pre>
<p class="commentary">leads to:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">kind</span><span class="plain-syntax"> K4_door &lt;= K1_thing </span><span class="identifier-syntax">__append</span><span class="plain-syntax">=</span><span class="string-syntax">" has door, "</span>
</pre>
<p class="commentary">Whereas to some extent <span class="extract"><span class="extract-syntax">insert</span></span> can work even if the target is not I6, the
<span class="extract"><span class="extract-syntax">__append</span></span> annotation ties the program to I6 only. At some point we may
simply abolish the "Include... when defining..." feature from I7, and then
we'll gladly remove <span class="extract"><span class="extract-syntax">__append</span></span>. Consider it deprecated already.
</p>

<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. Assimilation markers.</b>Every symbol (other than a function name) whose definition was assimilated from
Inform 6-syntax code in the source of a kit is given the boolean annotation
<span class="extract"><span class="extract-syntax">__assimilated</span></span>.
</p>

<p class="commentary">In addition, if the definition is of a fake action or an object, the annotation
<span class="extract"><span class="extract-syntax">__fake_action</span></span> or <span class="extract"><span class="extract-syntax">__object</span></span> will be applied. For example:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">Constant</span><span class="plain-syntax"> </span><span class="identifier-syntax">Dozen</span><span class="plain-syntax"> = </span><span class="constant-syntax">12</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">Fake_action</span><span class="plain-syntax"> </span><span class="identifier-syntax">PluralFound</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">Object</span><span class="plain-syntax"> </span><span class="identifier-syntax">thedark</span><span class="plain-syntax"> </span><span class="string-syntax">"(darkness object)"</span><span class="plain-syntax">;</span>
</pre>
<p class="commentary">assimilates to:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">package</span><span class="plain-syntax"> Dozen_con _plain</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> Dozen = </span><span class="constant-syntax">12</span><span class="plain-syntax"> </span><span class="identifier-syntax">__assimilated</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">package</span><span class="plain-syntax"> ##PluralFound_con _plain</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> ##PluralFound = </span><span class="constant-syntax">0</span><span class="plain-syntax"> </span><span class="identifier-syntax">__assimilated</span><span class="plain-syntax"> </span><span class="identifier-syntax">__fake_action</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">package</span><span class="plain-syntax"> thedark_con _plain</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">constant</span><span class="plain-syntax"> thedark = </span><span class="constant-syntax">0</span><span class="plain-syntax"> </span><span class="identifier-syntax">__assimilated</span><span class="plain-syntax"> </span><span class="identifier-syntax">__object</span>
</pre>
<p class="commentary">See the Inter test case <span class="extract"><span class="extract-syntax">Assim</span></span>.
</p>

<p class="commentary">These three markers are applied only during assimilation, and thus only by Inter.
The main Inform 7 compiler never applies them.
</p>

<p class="commentary">It would be feasible to combine these three annotations into a single one, say
<span class="extract"><span class="extract-syntax">__assimilated_from="DIRECTIVE"</span></span>, marking everything with the I6 directive it
came from. But while that would be elegant it would cost storage and time.
Boolean annotations are cheaper, and <span class="extract"><span class="extract-syntax">__assimilated</span></span> occurs a lot.
</p>

<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. Miscellaneous code-generation storage.</b>As noted above, the main use case intended for annotations is as a way for
optimisation or code-generation pipeline steps to attach notes to the tree.
These are of no significance once those steps are complete, and do not change
the meaning of the program.
</p>

<p class="commentary">They can also come or go without notice; they are not really part of the Inter
specification at all. But briefly, the current set used is:
</p>

<p class="commentary"><span class="extract"><span class="extract-syntax">__inner_property_name="NAME"</span></span> is used by <a href="../final-module/2-vo.html" class="internal">Vanilla Objects (in final)</a> to mark
which property name belongs to which two-word property array.
</p>

<p class="commentary"><span class="extract"><span class="extract-syntax">__object_kind_counter=NUMBER</span></span> is used by <a href="../pipeline-module/5-knd.html" class="internal">Kinds (in pipeline)</a> to number off
the kinds of object found in the program.
</p>

<p class="commentary"><span class="extract"><span class="extract-syntax">__array_address=NUMBER</span></span> is used by <a href="../final-module/5-cmm.html" class="internal">C Memory Model (in final)</a> to mark the
address in process memory of each array.
</p>

<p class="commentary"><span class="extract"><span class="extract-syntax">__global_offset=NUMBER</span></span> is used by <a href="../final-module/4-i6gv.html" class="internal">Inform 6 Global Variables (in final)</a> to
mark where in its array of global variables a given variable lives.
</p>

<nav role="progress"><div class="progresscontainer">
    <ul class="progressbar"><li class="progressprev"><a href="M-ip.html">&#10094;</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-ui.html">ui</a></li><li class="progresssection"><a href="M-ti.html">ti</a></li><li class="progresssection"><a href="M-dpiti.html">dpiti</a></li><li class="progresssection"><a href="M-cpiti.html">cpiti</a></li><li class="progresssection"><a href="M-ip.html">ip</a></li><li class="progresscurrent">ia</li><li class="progresssection"><a href="M-io.html">io</a></li><li class="progresssection"><a href="M-pas.html">pas</a></li><li class="progresssection"><a href="M-rc.html">rc</a></li><li class="progresschapter"><a href="1-mn.html">1</a></li><li class="progressnext"><a href="M-io.html">&#10095;</a></li></ul></div>
</nav><!-- End of weave -->

		</main>
	</body>
</html>

